---
description: Универсальный компонент для создания раскладок с поддержкой отступов, размеров, позиционирования и flex-свойств.
---

<Overview group="layout">

# Box [tag:component]

Компонент построен на базе системы отступов VKUI и предоставляет гибкий способ создания раскладок в приложениях VKUI,
позволяя задавать отступы, размеры, позиционирование и flex-свойства, делая процесс верстки более декларативным и предсказуемым.

</Overview>

## Когда использовать [#when-to-use]

Компонент `Box` рекомендуется использовать в следующих ситуациях:

- **Создание контейнеров с отступами**: когда нужно добавить внутренние отступы к любому элементу интерфейса;
- **Управление размерами**: для явного задания ширины, высоты или их ограничений;
- **Абсолютное и относительное позиционирование**: при создании наложений, выпадающих меню или сложных макетов;
- **Flex-элементы**: как потомок flex-контейнера.

<Playground>
  ```jsx
  <Group header={<Header>Заголовок группы</Header>} separator="hide">
    <Box paddingInline="var(--vkui--size_base_padding_horizontal--regular)" paddingBlock="m">
      <Text>
        <strong>Совет:</strong> Используйте Box вместо обычных div-элементов, когда вам нужны
        layout-свойства. Это обеспечит консистентность с дизайн-системой VKUI и упростит поддержку
        кода.
      </Text>
    </Box>
  </Group>
  ```
</Playground>

## Свойства раскладки [#layout-props]

Компонент `Box` поддерживает обширный набор свойств, объединенных в логические категории:

### Отступы [#padding]

Свойства отступов (свойства с префиксом `padding*`) позволяют управлять пространством вокруг содержимого. Они принимают:

- токены дизайн-системы VKUI (`'2xs', 'xs', 's', 'm', 'l', 'xl', '2xl', '3xl', '4xl'`);
- стандартные CSS-значения (`'inherit'`, `'initial'`, `'unset'`);
- числовые значения (будут преобразованы в пиксели);
- любое валидное строковое значение (`"2rem", "10%"`, CSS-переменные).

<Playground>
  ```jsx
  <Card Component="div">
    <Box paddingInline="2xl" paddingBlock="2rem">
      <Text>Есть возможность задать отступы со всех сторон</Text>
    </Box>
  </Card>
  ```
</Playground>

### Размеры [#size]

Свойства размеров (свойства с постфиксом `*Size`) позволяют управлять шириной и высотой компонента, включая минимальные и максимальные ограничения.
Они принимают:

- стандартные CSS-значения (`'auto'`, `'max-content'`, `'min-content'`, `'fit-content'`, `'inherit'`, `'initial'`, `'unset'`);
- числовые значения в пикселях;
- любое валидное строковое значение (`"200px", "50%"`, CSS-переменные).

<Playground>
  ```jsx
  <Card Component="div">
    <Box padding="m" inlineSize="100px" blockSize="70px">
      <Icon56GhostOutline />
    </Box>
  </Card>
  ```
</Playground>

### Позиционирование [#position]

Свойства позиционирования позволяют определять схему позиционирования и смещения для компонента Box, обеспечивая статическое, относительное, абсолютное или фиксированное позиционирование с направленными смещениями.

Свойство `position` принимает значения `'static', 'relative', 'absolute', 'fixed'`.

Свойства с префиксом `inset*` принимают:

- токены дизайн-системы VKUI (`'2xs', 'xs', 's', 'm', 'l', 'xl', '2xl', '3xl', '4xl'`);
- стандартные CSS-значения (`'auto'`, `'inherit'`, `'initial'`, `'unset'`);
- числовые значения (будут преобразованы в пиксели);
- любое валидное строковое значение (`"2rem", "10%"`, CSS-переменные).

<Playground>
  ```jsx
  <Card Component="div">
    <Box padding="4xl" maxInlineSize={200}>
      Демонстрация абсолютно-позиционированного блока с иконкой
    </Box>
    <Box position="absolute" insetInlineEnd="m" insetBlockStart="m">
      <Icon16MoreVertical />
    </Box>
  </Card>
  ```
</Playground>

### Flex-свойства [#flex-props]

Flex-свойства (`flexGrow`, `flexShrink` и `flexBasis`) позволяют управлять поведением компонента внутри `flex`-контейнера.

Данные свойства принимают стандартные CSS-значения (`'inherit'`, `'initial'`, `'unset'`).

Свойства `flexGrow` и `flexShrink` также принимают числовые значения.

`flexBasis` дополнительно принимает:

- `'auto'`, `'max-content'`, `'min-content'`, `'fit-content'`, `'content'`;
- числовые значения (будут преобразованы в пиксели);
- любое валидное строковое значение (`"2rem", "10%"`, CSS-переменные).

<Playground>
  ```jsx
  <Flex direction="column">
    <Box>1</Box>
    <Box flexBasis={50}>2</Box>
    <Box>3</Box>
  </Flex>
  ```
</Playground>

### Переполнение [#overflow]

Свойства переполнения (с префиксом `overflow*`) позволяют управлять отображением содержимого, которое выходит за границы компонента
Они принимают стандартные CSS-значения переполнения, такие как `'visible'`, `'hidden'`, `'clip'`, `'scroll'`, `'auto'`, `'inherit'`, `'initial'`, `'unset'`.

```jsx
<Box
  style={{
    border: '1px solid var(--vkui--color_separator_primary)',
    padding: '16px',
    margin: '16px 0',
    borderRadius: '8px',
    backgroundColor: 'var(--vkui--color_background_secondary)',
  }}
>
  <strong>📏 Единицы измерения:</strong> Все свойства принимают значения дизайн-системы VKUI
  (`'2xs'`, `'xs'`, `'s'`, `'m'`, `'l'`, `'xl'`, `'2xl'`, `'3xl'`, `'4xl'`), CSS-значения (`'auto'`,
  `'inherit'`, `'initial'`, `'unset'`) или числовые значения в пикселях.
</Box>
```

## Сравнение с другими компонентами [#comparison]

### Box vs Flex

- **Box** — универсальный контейнер с настраиваемыми отступами, подходит для создания изолированных блоков,
  может быть потомком компонента `Flex`;
- **[`Flex`](/components/flex)** — специализированный контейнер для создания flex-блоков, поддерживает все flex-свойства.

### Box vs div

- **Box** — предоставляет декларативный API на базе дизайн-токенов VKUI;
- **div** — требует ручного управления стилями и классами (через свойства `style`/`class`).

```jsx
<Box padding="m" inlineSize={300} position="relative">
  Контент
</Box>

<div style={{ padding: 'var(--vkui--spacing_m)', width: 300, position: 'relative' }}>Контент</div>
```

### Box vs Spacing

- **Box** — для создания контейнеров с любыми layout-свойствами;
- **[`Spacing`](/components/spacing)** — исключительно для создания отступов между элементами.

## Свойства и методы [#api]

<PropsTable name="Box" />
